home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 476-500 / disk_494 / bref / bref.doc < prev    next >
Text File  |  1992-05-06  |  9KB  |  262 lines
  1.  
  2.     Documentation for Program BREF            May 1991
  3.         Version 2.0    WorkBench or CLI executable
  4.         Dick Taylor  Glastonbury, Connecticut USA
  5.  
  6.                   Contents
  7.  
  8.     1. Components            7. Options
  9.     2. What does BREF do?        8. Program Limitations
  10.     3. How to use            9. Potential Problems
  11.     4. ASCII file for input        10. Program History
  12.     5. Operational description    11. Programming Notes
  13.     6. FileWindow            12. BREF Communications
  14.  
  15.  
  16.  
  17. 1. COMPONENTS
  18.  
  19. bref     -- executable
  20. bref.c, bref2.c, bref3.c, bref4.c  -- C language source code modules
  21. bref.doc -- documentation
  22. HSI.Color -- Basic code sample in ASCII
  23.  
  24.  
  25.  
  26. 2. WHAT DOES BREF DO?
  27.  
  28. BREF makes a Cross Reference Table for AmigaBASIC code.  This consists of a
  29. numbered listing of the BASIC code, plus a table showing variable/label
  30. usage.  Highly useful tool for Basic programmers.  Printer output recom-
  31. mended.  This version, 2.0 , is executable from WorkBench or CLI/Shell.
  32.  
  33.  
  34.  
  35. 3. HOW TO USE
  36.  
  37.     ==>  Your BASIC code must be in ASCII, not the default binary  <== 
  38.  
  39. Workbench:  Double click the BREF icon, follow directions for specifying
  40.         options and input.
  41.  
  42. CLI/Shell, printer output:  bref >prt: prog.name
  43.  
  44.     Can specify options; see #7.
  45.  
  46.  
  47.  
  48. 4. ASCII File for BREF input
  49.  
  50. To save your BASIC code in ASCII, use the BASIC output window:
  51.  
  52.     LIST ,"prog.name"
  53.  
  54. If you try to run BREF with saved binary, the run aborts with this message:
  55.  
  56.     "File prog.name is binary, can't process.  ASCII req."
  57.  
  58. You can also use the  SAVE "prog.name",a  command to make an ASCII file, but
  59. this has a drawback:  It changes the default mode of this program for this
  60. session to ASCII, and any further saves of any type will be in ASCII until
  61. you specify binary.  Avoid this "GOTCHA!" by using LIST.
  62.  
  63.  
  64.  
  65.  
  66.  
  67.   
  68. 5. OPERATIONAL DESCRIPTION
  69.  
  70. a. CLI/Shell-- command line is the sole user interface, same as v1.01.
  71.     Exception:  Invoke with just "bref", no arguments, gives WB mode.
  72.  
  73. b. WorkBench-- there are 4 displays to provide the user interface.
  74.     --OPTION  Displays 8 options with default settings, and provision
  75.         to change them.  Click buttons for HELP, SAVE, OK.
  76.     --HELP  A series of displays with usage information.
  77.     --FileWindow   Input selector.  Click buttons: OPTION, HELP,
  78.         GO = start execution, CANCEL = end run.
  79.     --ERROR  Display error message.
  80.  
  81.     SAVE of Options:  When you click on the SAVE button of the OPTION 
  82. display, the current settings of all 8 options are written out to a file
  83. in the current directory (filename = BREF.Option), and exit OPTION display.
  84.     For WorkBench execute, the program starts by looking for the saved
  85. options file.  If not found, it starts with the OPTION display.  If found,
  86. it restores the options from the file and starts with FileWindow.  You can,
  87. or course, go to OPTION for further changes if desired.
  88.     The OK button on OPTION uses the current settings for the run, but
  89. does not save them.
  90.  
  91. c. Abort execution:    CLI/Shell --    CTRL/C
  92.             WorkBench --    Click on CloseWindow
  93.             CLI, no arguments -- Either of above
  94.  
  95.  
  96.  
  97. 6. FILEWINDOW
  98.  
  99.     On initial display, FW shows the contents of the current directory--
  100. both directories and files.  Can click on a directory to show its contents.
  101. Just click on the file you want for input, & click GO to start execution.
  102.     You can scroll the display with the slider bar.
  103.     You can click-select a unit for display--  df0:  df1:  dh0:  ram:
  104.     You can click on "<" to back up to the parent directory.
  105.     You can enter a filename suffix in the "Ext" field, and then only
  106. filenames with that ending will be displayed, along with all directories.
  107.     You can click in File or Drawer/File to type in your input name or
  108. path/name.  For File, press of RETURN starts execution, same as GO.
  109.  
  110.  
  111.  
  112. 7. OPTIONS
  113.  
  114. 7.1 - Workbench
  115.  
  116. Use the OPTION display to set options as desired.  You can click on the
  117. "HELP" box to review on-line how to use the options.
  118.     Note on OUTPUT NAME option:  Default setting is "PRT:" = printer.
  119. Can change this to any file specification wanted, with one exception --
  120. If invoking from WorkBench, cannot get screen output directly.  If invoke
  121. from CLI (no arguments), can use * for direct screen output.  Of course you
  122. can easily get indirect screen output by directing output to a temporary
  123. file (ram:Temp for example), and then view this with an edit program.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. 7.2 - CLI/Shell
  135.  
  136. The first letter of each option may be upper or lower case.  Here is an
  137. example of running BREF with options:
  138.  
  139.     bref >prt: -Q -W132 your.prog.name
  140.  
  141. Specify as many options as needed; place preceding the program name, any 
  142. order.  Precede each option with a minus sign.
  143.  
  144. -Q    -don't print the BASIC code listing (Quiet).
  145. -Wnnn    -set page Width to nnn instead of default 80; max is 132.
  146. -Lnnn    -set page Length to nnn instead of default 66.
  147. -Hccc    -set page Heading to 'ccc' rather than the program name.
  148. -S    -Suppress Form Feeds; useful for screen output.
  149. -K    -show the BASIC Keywords in the the cross ref table.
  150.      Default-- the BASIC keywords are omitted.
  151. -E    -print the BASIC code 12 char's/inch (Elite type) instead of
  152.      the default 10 char's/inch.  For a default 80-char
  153.      line, this produces a 96-char line.  This tends to cut down on 
  154.      the annoying lines which are split into 2 lines on printing.
  155. -?    -display this list.
  156.  
  157.  
  158.  
  159. 8. PROGRAM LIMITATIONS
  160.  
  161.    a.  Max name size:  AmigaBASIC 40 char's; BREF 15 char's.
  162.    Names longer than 15 char's appear in BREF table split in parts.
  163.  
  164.    b.  BREF uses up to four digits (9999) for the assigned line numbers,
  165.    enough for 180+ pages.  For > 9,999 lines, split in parts to process.
  166.  
  167.  
  168.  
  169. 9. POTENTIAL PROBLEMS
  170.  
  171. 9.1    WorkBench Version Serious Error
  172. If the WB version has a serious problem such as failing to open Intuition
  173. or the Window, you will not see any of the error messages; the run will
  174. just terminate.  You can easily repeat the situation by running from
  175. CLI/Shell with just "BREF", no command line arguments.  This will run
  176. BREF in WB mode, and you should see any error messages in the CLI window.
  177.  
  178. 9.2     Stack
  179. BREF makes heavy use of recursion, which is a stack-intensive operation. 
  180. In running very large BASIC programs through BREF, it is possible that you
  181. may crash the system (guru or whatever) due to exceeding the stack (default
  182. stack size is 4000).  If this happens, try increasing the stack to 8000 and
  183. rerun.  The largest program I have run is a little over 1,000 lines-- no
  184. problem with the default stack.
  185.  
  186.  
  187.  
  188. 10. PROGRAM HISTORY
  189.  
  190.     BREF is a modification of CREF, the C language cross referencer.
  191. CREF appears on Fred Fish Disk #166.  It was written by Mike Edmonds in
  192. 1981, and ported to the Amiga by Joel Swank in 1987.  I produced the initial
  193. BREF v1.01 in 1989; it appears on FF#283.  The present version of BREF
  194. benefits greatly from use of Anders Bjerin's routine FileWindow for input
  195. selection.  Thanks Anders!!
  196.  
  197.  
  198.  
  199.  
  200.     Credits:  Thanks to:  BOB BROMLEY, Malton Ontario Canada, and 
  201.     DOUG NELSON, Omaha Nebraska, for suggested improvements, bug
  202.     reporting and testing;  KARL RIESEN, Oberrieden Switzerland, for
  203.     suggesting the WorkBench executable version, and invaluable ideas,
  204.     advice, and testing to reach this goal; artist/son ALAN TAYLOR
  205.     for the "Bee"-REF icon, made with Deluxe Paint.
  206.  
  207.  
  208. 11. PROGRAMMING NOTES
  209.  
  210.   a. BREF was compiled with Manx Aztec C v. 5.0:
  211.     cc -wn bref.c
  212.     cc -wn bref2.c
  213.     cc -wn bref3.c
  214.     cc -wn bref4.c
  215.     ln bref.o bref2.o bref3.o bref4.o -lm -lc
  216.  
  217.   b. Program changes to CREF to produce BREF:
  218.     -AmigaBASIC keyword list, 202 items
  219.     -Char set for word definition: drop # _  add . % & ! # $
  220.     -Comment definition: ' or REM
  221.     -Default print line 80 char (was 132)
  222.     -Add options -S, -K, -E
  223.     -Assigned line no. print field width 4 char (was 6)
  224.  
  225.   c. I encountered significant trouble with implementing the AmigaBASIC
  226. keyword list.  When I entered the list in alphabetic order and tried to run
  227. with stack = 4000, it crashed (guru) in a variety of places depending on
  228. other system factors.  It turns out to be a problem caused by heavy
  229. recursion usage -- entering items (both keywords and program words) into a
  230. tree.  The solution was to enter the keywords in binary search order,
  231. thereby minimizing recursion level depth.  With this arrangement of
  232. keywords I've had no problem running with stack of 4000.
  233.  
  234.   d. Aztec C V 5.0 Date Anomaly:  The Amiga standard time value is --
  235.     "Seconds since Jan 1, 1978"
  236. V 5.0 has changed this standard to --  "Seconds since Jan 1, 1970"
  237. Functions time() and ctime() use this convention. 
  238.  
  239. Problem:  If you use ctime() to print a file date (Amiga DOS),
  240. the date is 8 years too old.  I have patched the problem by adding
  241. a constant (252460800 -- 1970 to 1978 in sec's) to the input file time
  242. value before passing it to ctime().
  243.  
  244.   e. The FileWindow routine appears on FF #336, was written by Anders
  245. Bjerin of Lidingo, Sweden.  Anders encourages others to use/modify this
  246. routine in any way desired, which is what I have done:
  247.   -Delete gadgets SAVE, DELETE
  248.   -Rename gadget LOAD to GO
  249.   -Add gadgets ram:, HELP, OPTION
  250.   -Replaced function stricmp() (not available in Aztec) with strcmp(),
  251.     but with added processing to put the strings in lower case
  252.     before the compare.
  253.  
  254.  
  255. 12. FOR BREF COMMUNICATIONS--
  256.  
  257.     Dick Taylor        If you've found a program bug,
  258.     99 Valley View Rd    or have a program change to suggest,
  259.     Glastonbury CT         or want to correspond,
  260.     06033-3621  USA        I'll be glad to hear from you.
  261.     Tel (203) 633-0100
  262.